Skip to content

fix(terminal): a clear partway through a control sequence no longer leaves stray characters on screen - #42

Open
viktorce wants to merge 1 commit into
mainfrom
fix/terminal-clear-live-screen
Open

viktorce wants to merge 1 commit into
mainfrom
fix/terminal-clear-live-screen

Conversation

@viktorce

@viktorce viktorce commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Fixes #38.

Clearing a terminal while a control sequence had half arrived made every attached client draw the other half as text.

A control sequence can reach a client in two pieces of output. On a cleared event, clearOutput in packages/client-runtime/src/state/terminalOutput.ts appends the erase text ESC[H ESC[2J ESC[3J to the terminal's output. The ESC that starts the erase text makes the emulator abandon the sequence it was reading. The emulator then draws the rest of that sequence as text.

clearOutput now appends the start of the unfinished sequence again, right after the erase text. The emulator reads the start a second time on the erased screen, and the rest of the sequence completes it. With no sequence open, a clear appends the same bytes as before.

A new helper, unfinishedTerminalSequence in packages/contracts/src/terminal.ts, finds that start with the model of Ghostty's parser states that the client already uses to trim output. Web, desktop and mobile all handle cleared through clearOutput.

The branch sits on e37e45fd5b. Fork main has moved to 57db750b8f since, with no change to the files this fix touches or reads.

What changes on screen

Each case prints before and the first part of a sequence, gets cleared, then prints the rest and after. ESC and BEL stand for those control characters, and the spaces next to them are for reading.

Sequence split around a clear Screen before Screen now
ESC[6n, the cursor-position query, split after ESC[6 nafter, and no reply after, and the reply ESC[1;1R
ESC[31m, a colour change, split after ESC[31 mafter in the default colour after in red
ESC[2;3H, a cursor move, split after ESC[2;3 Hafter on row 1 after at row 2, column 3
ESC]0;title BEL, a window title, split after ti tleafter after
ESC]8;;http://example.com ESC\, a hyperlink, split after exa mple.comafter after

In every row the screen now has the text, colours and cursor position of an emulator that starts empty and gets the whole sequence and after in one piece. The rows come from a throwaway probe against the web client's real Ghostty core. The committed Ghostty test covers rows 1 and 4.

Before you merge: output that main drops at a clear

main still drops queued output at a clear, which is #9 and which #30 fixes. When the rest of an open sequence was in that dropped output, the sequence this PR reopens takes its ending from whatever comes next.

Delivered, then dropped at the clear, then printed Screen before Screen now
busy ESC[6, then n dropped, then hello hello ello, because the h ends ESC[6h
busy ESC[?1049, then the rest dropped, then hello hello ello on the alternate screen, because the h ends ESC[?1049h
busy ESC]0;ti, then the rest of the title dropped, then hello hello nothing, until the string ends

It needs the paused delivery behind #9, which about 100,000 clears in the running app did not reach. The bug this PR fixes needs no paused delivery.

The client cannot tell that the server dropped output, so it cannot avoid this. The owner decided that this PR targets main and does not wait for #30.

Why the start is sent again, and the erase is not held back

A sequence takes effect when its last character arrives. For a split sequence that is after the clear, so the result should be the erased screen with the sequence applied to it. Erase, then ESC[2;3H, puts after at row 2, column 3. Holding the erase back until the sequence ends would run the move first and the erase second. The erase homes the cursor, and after would land on row 1. #34 makes the same choice for the saved history.

The helper starts at the last ESC in the retained output, because an ESC starts a new sequence from every parser state. It returns nothing when the output ends outside a sequence, or no longer holds that ESC.

It leaves out C0 controls, such as LF and TAB, that arrived inside an escape or CSI sequence. Ghostty runs those when they arrive, and sending them again would run them twice. Inside a string they are string content or ignored, and the helper keeps them.

How this relates to #33 and #34

It is the same split, seen from two sides. #33 is about the server's saved history, which a client gets when it attaches, reconnects or reopens the terminal. #34 fixes that and is stacked on #30. This PR is about the screen of a client that stays attached.

Neither fix needs the other's code. This PR changes packages/client-runtime, packages/contracts and a test in apps/web. #34 changes only apps/server/src/terminal/Manager.ts and its test file.

They do belong together. I compared the live screen with a replay of the saved history in nine split cases. Either fix alone makes them disagree in 8 of the 9. With both, all nine agree and none shows stray text.

How the comparison was made
Server Client Live screen equals the replayed history
main main 9 of 9, and 8 of the 9 show text that should not be there
#34 at b5c9783bac main 1 of 9
main this PR 1 of 9
#34 at b5c9783bac this PR 9 of 9, none with stray text

The one case that always agrees has no open sequence.

The nine cases are a query, a colour change, a cursor move, a bare ESC, a title string ended by BEL, a title string split inside its ESC \ end, a hyperlink, a string that never ends, and a clear with no open sequence. A throwaway server test printed the saved history for each case, on e37e45fd5b and on #34's head. A throwaway Ghostty test then compared whole screen snapshots of the live client with an emulator reset and fed each history. Neither is committed.

On main with main, seven cases show the same stray text on both sides. In the eighth, the string that never ends, both show plain text, which the string should have swallowed.

The client side ran on this PR's first head, d1ca3fe7e5. None of the nine cases has a control inside an escape or CSI sequence, so the final code sends the same bytes in all nine.

A string that never ends

A program can start an OSC, DCS, PM or APC string and never end it. The emulator then swallows all later output. #37 covers what that does to the server.

Before this PR, a clear ended such a string on the client as a side effect of the erase text's ESC, and the stuck emulator drew again. Nothing tested it.

The decision: on the client, a clear leaves an open string open, at any size the client still retains. The client sends the string's start again like any other unfinished sequence, so after the erase the emulator is back inside the string until it ends. With before ESC]0;stuck, a clear, then plain text, the screen showed plain text before and shows nothing now.

Why:

  1. When the clear arrives, the client cannot tell a string that never ends from a string whose end is in the next piece of output. Ending the second kind at the clear is this bug.
  2. fix(server): terminal history keeps a control sequence whole across a clear #34 makes the same choice for the saved history, where the server keeps holding the open string after a clear. With both, the screen and the history agree.
  3. The clear is not something the program printed, so it has no reason to end what the program is partway through.

The mobile text fallback follows the same rule. Right after a clear it starts empty, as before. When later output trims the buffer inside the reopened string, the fallback hides the rest of that string, as it already does with no clear. Before, the clear had ended the string and that text showed. With a 16-byte buffer, ESC]0;, a clear, then abcdefghijklmnop showed the 16 letters before and shows nothing now. With no clear it shows nothing on both.

What still ends the string is what ends it with no clear: an ESC, a CAN or a SUB from the program, a BEL for an OSC, a new snapshot when the client attaches again, or restarting the terminal. In a DCS, PM or APC string, a character whose UTF-8 bytes include one from 0x80 to 0x9F ends it, or starts another sequence. Once an open string has grown past what the client keeps, the last 512 KiB of output by default, its ESC is gone, and a clear ends the string as it does today.

What gets worse

The clear key no longer gets a frozen screen drawing again. A terminal stuck inside a string that never ends stays stuck after a clear, where before the erase text ended the string.

A large open string is stored again at each clear. A probe printed an unended 400 KiB string and cleared five times with no output between. Retained output went from 409,610 bytes to 2,457,685, against a budget of 524,288, where before it went to 409,665. The next output trims back to the budget and evicts everything older, including output that set modes. With no output between, growth stops only at the 1,024-chunk limit, near 16 MB. With ESC[?1h printed first, that limit started evicting at clear 39, and from clear 40 retained output stayed at 16,122,456 bytes with the mode-setting output gone. The replay then no longer extends the one before, so an older mobile binary recreates its emulator, without the mode. Before, 60 clears ended at 410,269 bytes. Each clear also feeds the whole open string through the emulator of every attached client.

I added no size limit. #37 asks for one only for the text the server holds, and nothing tracks this cost on the client yet.

An OSC query is answered once more at each clear. Ghostty acts on an OSC string when the string ends, however it ends. That includes the erase text cutting it short, which is not new. A CAN or a SUB in place of the ESC behaves the same, so the erase cannot end a string quietly. With the start sent again, Ghostty acts on the string again when it really ends. For a string that sets something, such as a title, the whole string is applied last. What the cut-short string did before it is not undone, and that part is not new. For a query, the program gets one extra reply for each clear that lands after a complete query inside the string:

Query split around a clear Replies before Replies now With no clear
ESC]11;? BEL, split right before the BEL 1 2 1
ESC]11;? BEL, two clears right before the BEL 1 3 1
ESC]11;? BEL, split after ESC]11 0, and ;? drawn as text 1 1
ESC]4;1;?;2;? BEL, split after 1;? 1, and ;2;? drawn as text 3 2

The reply goes to the pty. If the program that asked has stopped reading, whatever reads next gets it, usually the shell's line editor.

I kept the extra reply because the ways around it cost more. The client would have to know which OSC commands reply, or hold the erase back until a string ends, which a string that never ends would block for good.

These observations come from the web wasm build, which shares Android's Ghostty revision. A CSI sequence acts only at its final character, so ESC[6 cut short by the erase drew no reply. DCS and APC drew no reply, cut short or whole.

The rest is inferred, not observed. iOS runs full Ghostty, which may answer DCS and APC queries, so an extra reply is possible there too. A string that acts once each time it ends, such as an OSC 9 notification, would act once more for each clear.

Mobile

Only the mobile app has a clear key. It sends terminal.clear, and the server sends cleared to every client attached to that terminal. Web sends Ctrl+L to the shell instead, see #9. So a web or desktop client hits this only while a mobile client clears the same terminal.

What I ran: the session test, which pins what each mobile path below gets, the Ghostty test, and mobile's own 41 terminal tests, which pass unchanged. The Ghostty test runs Android's parser source on a different target, since Android pins the web wasm's Ghostty revision, 3ff6d08fad56f2d6b81420a27bdc56ee707b453e, and its two patches leave the parser alone.

What I did not run:

  • The native emulator on any iOS or Android device or simulator. Agent device access is off here, and this Mac has no iOS simulator. Nobody has pressed the clear key against this fix.
  • iOS's parser. iOS uses a different Ghostty build, GhosttyKit.xcframework from a fork, with no slice that runs on a Mac. The shared model decides which bytes are sent again, not the emulator.
  • An integrated pass in the web app, which could send terminal.clear as a plain RPC with no mobile client. The Ghostty test already runs the real reducer, reader, writer and core, so the pass would add only the transport, which this PR does not change.

To check by hand on a device, run printf 'before\033[31'; sleep 10; printf 'mafter\n' in the terminal and tap the clear key during the sleep. Before this PR the screen shows mafter in the default colour. With it the screen should show after in red.

The three ways output reaches a mobile screen

Mobile handles cleared through the same applyTerminalAttachStreamEvent and clearOutput as web.

  1. Current native builds read readTerminalOutputUpdate through createTerminalOutputWriter and feed the bytes to native Ghostty. iOS calls ghostty_surface_feed_data. Android uses libghostty-vt.
  2. Older installed binaries get terminalOutputReplay as initialBuffer. They recreate their emulator unless the new buffer extends the last one. The session test uses a full buffer and a string with a two-byte character, so it fails if a clear trims the buffer.
  3. With no native view, the text fallback draws terminalOutputText, and draws escape sequences as plain text. Right after a clear it starts empty and shows the rest of a split sequence as text, nafter, as before. Trimming inside a reopened string is the one case that differs, see "A string that never ends".

The web wasm is built from the revision in native/libghostty-vt/VERSION, and runtimeAbi.test.ts checks it against that file. The Android build script pins the revision by itself and does not read that file.

Tests

  • packages/contracts/src/terminal.test.ts, "unfinishedTerminalSequence", one table of eight rows for the helper.
  • packages/client-runtime/src/state/terminalSession.test.ts, "sends the start of an unfinished control sequence again after the erase". The title string arrives in two outputs and fills a 16-byte buffer. The test checks the bytes a live reader gets, the replay for older binaries, extended and not trimmed, and the empty fallback text.
  • apps/web/src/terminal/ghostty/core.test.ts, "completes a control sequence that a clear splits", two rows. Each compares the whole screen snapshot and the replies with an emulator that gets the sequence in one piece. The rows take different paths in Ghostty, since the erase makes it act on an unfinished OSC and not on an unfinished CSI.

All three fail without the fix, and each of twelve single-change mutations fails at least one. vp run check:changed and the terminal suites pass: 12 tests in packages/contracts, 31 in packages/client-runtime, 95 in apps/web across the Ghostty core, surface, ABI and drawer files, and 41 in apps/mobile.

Test transcripts, on base and on this branch

The issue's test, added verbatim before any change, failed on e37e45fd5b with expected 'nafter' to be 'after' and expected 'mafter' to be 'after'. The committed tests replace it.

Base below means terminalOutput.ts and packages/contracts/src/terminal.ts from e37e45fd5b, with this branch's tests. The helper does not exist there, so its table fails with unfinishedTerminalSequence is not a function.

base e37e45fd5b
 src/terminal.test.ts                   Tests  8 failed | 4 passed (12)
 src/state/terminalSession.test.ts      Tests  1 failed | 13 passed (14)
   × sends the start of an unfinished control sequence again after the erase
 src/terminal/ghostty/core.test.ts      Tests  2 failed | 38 passed (40)
   × completes a control sequence that a clear splits (a query)
   × completes a control sequence that a clear splits (a title string)

this branch
 src/terminal.test.ts                   Tests  12 passed (12)
 src/state/terminalSession.test.ts      Tests  14 passed (14)
 src/terminal/ghostty/core.test.ts      Tests  40 passed (40)
Mutations: twelve single changes, each fails a test
Mutation Fails
Send nothing again session test, Ghostty test, both rows
Start at the first ESC, indexOf for lastIndexOf helper table, "a query after a finished colour change"
Keep controls inside a CSI helper table, "a CSI holding a space and a line feed"
Keep controls inside an escape helper table, "an escape holding a tab and a backspace"
Drop controls inside a string helper table, "a title string holding a line feed"
Old budget, the erase text's length only session test, the replay is trimmed
Budget counted in code units, not bytes session test, the replay is trimmed
Send again a sequence that has ended helper table, "text after a finished sequence" and "an ended title string"
Fallback text starts at the sequence start session test, the text is not empty
Scan only the last chunk, current.chunks.at(-1)?.data ?? "" session test, the bytes a live reader gets lack the string's start
Drop the guard for text with no ESC, if (escape < 0) return ""; helper table, "text with no ESC"
Drop a space inside a CSI as a control, unit <= 0x20 for unit < 0x20 helper table, "a CSI holding a space and a line feed"
Upstream search

I searched pingdotgg/t3code again on 2026-11-19, issues and pull requests in every state, by keyword and by the files changed. I found no issue or PR for this bug. Upstream main at cb391b5b57 has the same terminalOutput.ts and parser model as this branch's base.

Related upstream work, by number only: PR 36380, merged 2026-11-13, introduced the erase text. PR 36368, merged the same day, added the parser model this fix uses. Open PR 34786 adds an unrelated function to the same file and leaves clearOutput alone. Open PRs 25192 and 22092 change what the server's clear does to queued events, which is #9 and #31 here.

Implemented by Claude Fable 5.2 and Claude Opus 5.5 in Claude Code (T3 Code). Reviewed by Claude Opus 5.5, Claude Fable 5.2 and GPT-6.1 Sol.

@github-actions github-actions Bot added vouch:trusted Author is trusted by repo permissions or the VOUCHED list. size:S labels Nov 19, 2026
@viktorce
viktorce force-pushed the fix/terminal-clear-live-screen branch from d1ca3fe to 0dbc1e6 Compare November 19, 2026 23:43
@github-actions github-actions Bot added size:M and removed size:S labels Nov 19, 2026
@viktorce
viktorce force-pushed the fix/terminal-clear-live-screen branch from 0dbc1e6 to 80b2519 Compare November 20, 2026 00:12
…eaves stray characters on screen

A control sequence can reach a client in two pieces of output. When a
`cleared` event arrived between them, the client appended the erase
text ESC[H ESC[2J ESC[3J to the terminal's output. The ESC that starts
it made the emulator abandon the sequence it was reading and draw the
rest as text. A cursor-position query, ESC[6n, split around a clear put
a stray "n" on the screen and was never answered. A colour change,
ESC[31m, put a stray "m" there and lost the colour.

clearOutput now sends the start of the unfinished sequence again after
the erase, so the rest completes it on the cleared screen. A new
contracts helper, unfinishedTerminalSequence, finds that start from
the last ESC with the shared parser model. It leaves out C0 controls
that arrived inside an escape or CSI sequence, because the emulator
already ran them. With no sequence open a clear sends the same bytes
as before. The text fallback still starts empty after a clear.

A string that a program never ends, such as an OSC with no terminator,
now stays open across a clear, where the erase text used to end it.
When later output trims the buffer inside such a string, the text
fallback hides the rest of it, as it already did with no clear.

Three cases get worse. A clear stores an open string again, so the
next output can evict older output, including output that set modes.
On a server that still drops queued output at a clear, the reopened
sequence takes its ending from whatever comes next, so ESC[6 with a
dropped "n" and then "hello" shows "ello". An OSC query gets one extra
reply for each clear that lands after a complete query inside the
string.
@viktorce
viktorce force-pushed the fix/terminal-clear-live-screen branch from 80b2519 to 3a84fa7 Compare November 20, 2026 00:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:M vouch:trusted Author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clearing a terminal partway through a control sequence leaves stray characters on the live screen

1 participant